Skip to content

Module authors have direct development and validation procedures - #565

Open
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
mainfrom
module-guide-writing-alignment
Open

Module authors have direct development and validation procedures#565
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
mainfrom
module-guide-writing-alignment

Conversation

@MariusStorhaug

@MariusStorhaug Marius Storhaug (MariusStorhaug) commented Nov 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Module authors get direct, evergreen procedures for bootstrap, coordinated development, framework-test exceptions, validation, module tests, and plugin-skill authoring. Descriptions state supported facts; procedures use active instructions and explicit conditions.

This change revises guidance only. It requires no module, workflow, configuration, or dependency migration. Executable examples and runtime/version constraints remain unchanged.

Changed: Module guides state direct procedures and supported facts

The six guides replace conversational, vague, and future-delivery wording with present-state descriptions and verifiable actions. The test guide names the v5.1.1 action contract that the workflow uses and states its unsupported optional-control limitation without a future implementation promise. Its Pester declaration keeps the exact minimum and maximum from the existing code block, without the misleading 6.1.x prose label.

The bootstrap version-policy conflict and OS-qualified shared-resource example conflict remain explicit follow-ups. This prose delivery does not choose a new version policy or change executable examples.

Technical details

Source comparison and delivery. Base 64ffb1d87f86bd5d487891fdb140b78385a00531; final pushed head d33a7e1773f9bde2527ae94fea7a8ed2c22a4acf. Six small commits are pushed. This draft opened immediately after the first coherent commit, 5f5062cca628831bc4f3de8864c84bb2759ed6f7. It stays in draft by request. No merge, auto-merge, Agent merge, or additional child session is used.

Manual review and before/after evidence. Every assigned file is read in full before edits and in the final review, including unchanged passages and examples. All six files change; no assigned guide is omitted or given an unverified no-change result.

Exact changed path Before After
docs/content/get-started/module-bootstrap.md "the piece(s) every other function will depend on"; "first real release" "contains the components that all other module functions require"; "first release (v1.0.0)".
docs/content/guides/module-development-orchestration.md "a second place where the implementation is silently changed" "The orchestrator does not change a child's implementation without a recorded scope decision."
docs/content/guides/skipping-framework-tests.md "will cause the framework to skip"; "will log a warning" "The framework skips only the identified test for that file. It writes the supplied reason as a warning in the build output."
docs/content/guides/validating-before-review.md "current enough that generated documentation will stay accurate" "public-function links resolve and usage examples match the implemented parameters and outputs".
docs/content/guides/writing-module-tests.md "will expose them after"; "current v5.1.0"; a 6.1.x label for a broader declaration The pinned v5.1.1 contract does not accept the optional controls; the reusable workflow does not expose them. The declaration is introduced as "this Pester requirement".
docs/content/guides/writing-plugin-skills.md "an operational entry point for an agent; shared process and policy belongs" "A skill is an agent's entry point. Shared process and policy belong in the documentation".

Meaning and protected content. The immutable source comparison verifies 10 byte-identical fenced examples, 54 headings unchanged except sentence case, and all 85 distinct per-file inline technical tokens retained. Manual comparison preserves public inputs/defaults, paths, framework-test IDs, warning semantics, discovery precedence, bootstrap rules, caller-provided TestData, and normative requirement strength. No normative requirement is presented as proof of CI enforcement. No link repair requires another owner's file.

Writing sources. The fixed writing baseline is MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082: Natural Language, Writing Guide, Markdown, Documentation, Documentation Model, and the guide template.

The review also uses the STEMG description, STEMG FAQ, and ASD-STE100 Issue 9, including relevant writing rules and dictionary entries. The reference PDF and extraction stay local; the verified PDF MD5 is 9c720341c350ed77943b2c73d01c716f. No required writing source is unavailable. Automated checks do not prove full STE conformance.

Changed surface Standards checked Framework/source evidence checked Result
module-bootstrap.md Fixed writing baseline and guide template Existing bootstrap branch/release contract; versioning reference Exception - #573 preserves the policy conflict.
module-development-orchestration.md Fixed writing baseline and guide template Existing child scope, handoff, integration, and release-readiness contract Fixed in this PR.
skipping-framework-tests.md Fixed writing baseline and guide template Source-code FunctionCount skip handling and warning output Fixed in this PR.
validating-before-review.md Fixed writing baseline and guide template Module structure, native-help, and test reference requirements Fixed in this PR.
writing-module-tests.md Fixed writing baseline and guide template Discovery/settings source, test/setup/teardown workflows, and pinned action interface Exception - #571 preserves the executable sample conflict.
writing-plugin-skills.md Fixed writing baseline and guide template Existing plugin README, directory structure, plugin metadata, and marketplace registration Fixed in this PR.

Read-only inspections and justified no-change results. Supporting files/sections: README.md; AGENTS.md; .gitignore; .github/actions/Get-PSModuleSettings/src/main.ps1; .github/actions/Test-PSModule/src/tests/SourceCode/PSModule/PSModule.Tests.ps1; .github/workflows/workflow.yml; .github/workflows/Test-ModuleLocal.yml; .github/workflows/BeforeAll-ModuleLocal.yml; .github/workflows/AfterAll-ModuleLocal.yml; .github/workflows/Docs.yml; .github/workflows/Linter.yml; .github/workflows/Release.yml; .github/linters/.markdown-lint.yml; .github/linters/.textlintrc; .github/plugin/README.md; .github/plugin/psmodule/plugin.json; .github/plugin/marketplace.json; docs/zensical.toml; and the relevant sections of docs/content/reference/{versioning,powershell-module-standard,test-specification}.md. They need no edit because this delivery changes guide prose, not their contracts, implementation, native help, tests, metadata, or configuration.

The remote Invoke-Pester action contract is read at exact SHA c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb. The v5.1.1 tag independently resolves to that commit. Its interface lacks Run.Shuffle, Run.ShuffleSeed, Run.Parallel, Run.ParallelThrottleLimit, and Debug.ShowStartMarkers. Neither workflow action references nor Pester/runtime constraints change.

Exclusions. Every other repository path is excluded: other getting-started and guide pages, reference pages, indexes, specifications, dictionary pages, assets/site design, plugin skills/metadata, code, tests/assertions, and configuration. Reserved release/workflow/structure/configuration surfaces remain with #524, #525, #531, #535, #537, #541, #548, and #549. #551 changes no documentation or native help. Live open-PR path ownership is checked before every commit; no other PR owns an assigned path.

Checks on the final head.

Command or review Result
git diff --check 64ffb1d87f86bd5d487891fdb140b78385a00531 Pass.
npx --no-install markdownlint-cli2 --config .github\linters\.markdown-lint.yml with the six exact assigned paths Pass: 6 files, 0 issues.
zensical build --clean from docs Pass: "No issues found", exit 0.
Existing rules.terminology through TextlintKernel.lintText Pass: 6 final guides, 0 issues; an intentional Powershell positive control reports the PowerShell correction.
Standard-library scoped Markdown/generated-HTML link review Pass: 33 relative links, 9 rendered fragments, 0 issues.
Exact committed git show source comparisons Pass: 10 byte-identical fences, 54 stable headings, 85 retained per-file inline technical tokens, exact six-file scope.
Six original wording cases Each fails on the original baseline and passes at the final head. The additional misleading Pester-range label is absent.
ConvertFrom-Json on plugin and marketplace metadata Pass; both files are unchanged.

The direct terminology CLI is absent; the cache-only attempt confirms missing packages before a session-local restore. Its Windows CLI loader does not load the configured rule. The successful kernel invocation loads the existing Markdown parser and exact rules.terminology options from .github/linters/.textlintrc, with an active positive control. No repository dependency, linter, or configuration is added. No standalone link-check script exists in this snapshot; the scoped check uses Python's standard library and actual generated HTML. It does not claim exhaustive external-site validation. Generated site output and the temporary checker restore are removed after verification; the worktree is clean and local/remote commit counts are 0 0.

Hosted status on the final head. gh pr checks 565 --repo PSModule/Process-PSModule --json name,state,link reports 22 successful checks, one skipped Publish check, and no pending or failed checks. Copilot approves d33a7e1773f9bde2527ae94fea7a8ed2c22a4acf with "No open issues" and no inline comments. Final-head Build, Lint, Lint code base, CodeQL, and Analyze (actions) pass. No new local failure or scope blocker remains. The PR stays in draft for the requested acceptance review; these results do not authorize readiness or merge.

Plan and convergence. #559 contains the current Task plan, pre-edit evidence, final acceptance evidence, and check results. Its author-side implementation steps are complete; the issue stays open until the normal review/merge path completes. The scoped sweep examines campaign issue titles and declared paths, plus bootstrap/major, version-policy, and RUNNER_OS searches. Only #559 is fully covered. #571 and #573 remain non-closing follow-ups; other campaign issues name excluded surfaces. The docs-only path set does not invoke the release workflow, so no release-decision block or release:* label applies.

Related references

Open
9 tasks done
@github-actions

github-actions Bot commented Nov 4, 2026 •
edited
Loading

Copy link
Copy Markdown

Super-linter summary

Language Validation result
CHECKOV Pass ✅
CSS Pass ✅
CSS_PRETTIER Pass ✅
GITHUB_ACTIONS Pass ✅
GITHUB_ACTIONS_ZIZMOR Pass ✅
GITLEAKS Pass ✅
GIT_MERGE_CONFLICT_MARKERS Pass ✅
HTML Pass ✅
JAVASCRIPT_ES Pass ✅
JAVASCRIPT_PRETTIER Pass ✅
MARKDOWN Pass ✅
NATURAL_LANGUAGE Pass ✅
POWERSHELL Pass ✅
PRE_COMMIT Pass ✅
SPELL_CODESPELL Pass ✅
TRIVY Pass ✅
YAML Pass ✅

All files and directories linted successfully

For more information, see the GitHub Actions workflow run

Powered by Super-linter

Copilot AI previously approved these changes Nov 4, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues were identified for the documentation updates clarifying module-author procedures.

No open issues 🎉

What changed in this PR

Clarifies module-author procedures across three Process-PSModule guides. The changes update documentation only; they introduce no runtime behavior or workflow migration.

Changes:

  • Rewrites bootstrap instructions as direct steps while preserving the branch and release contract.
  • Clarifies per-file framework-test exceptions and how to document their reasons.
  • Simplifies module-test guidance and corrects the referenced Invoke-Pester action version to v5.1.1.
File Description
docs/​content/​guides/​writing-module-tests.md Clarifies test discovery, setup, teardown, shared resources, and supported Pester controls.
docs/​content/​guides/​skipping-framework-tests.md Makes skip instructions and exception guidance more direct.
docs/​content/​get-started/​module-bootstrap.md Clarifies core scope, integration-branch steps, and initial-release procedures.

Review effort: Balanced

Open
5 tasks
Copilot AI reviewed Nov 4, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the documentation-only updates clarifying module-author guidance.

No open issues 🎉

Review effort: Balanced

Copilot AI approved these changes Nov 4, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues are reported for this documentation-only update clarifying module-author procedures.

No open issues 🎉

Review effort: Balanced

This was referenced Nov 4, 2026
Open
Open
Open
Open
@MariusStorhaug
Marius Storhaug (MariusStorhaug) marked this pull request as ready for review November 4, 2026 14:43

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot approved these changes

Assignees

@MariusStorhaug Marius Storhaug (MariusStorhaug)

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[documentation-writing-alignment] Give module authors direct evergreen procedures

2 participants

@MariusStorhaug